*********************************
*** MULTIPLE SPLINEATTACH 1.2 ***
*********************************

MSA 1.2 let's you attach one or several objects along a spline.

****************************
*** HOW TO USE THE PLUG? ***
****************************

Basic workflow:

 * Create a spline that you want to place the objects along

 * Create an object group with objects in or use a single object

 * Create an animation track on the spline with a key

 * Adjust the parameters

Extra things:

 * Create an align spline

 * Create a scaling spline

 * Create more keys for animation

*******************
*** THE DIALOGS ***
*******************

MSA 1.2 uses an adaptive dialog system which means that what you enter in the 
earlier dialogs decides what dialogs will show up next. This is a guide to all
possible routes.

* First dialog: Multiple Splineattach Settings

  Group: 
    The name of the object group which contains the objects to be attached,
    or if in single mode the one object to attach.
  
  Rename: 
    see "NAME POSITIONING"

  Type: (G, NIG, S)
    1. attaches all objects inside the Group
    2. similarily but internal groups aren't attached
    3. attaches a single object (entered in group-field)

  Align and position type: (1 and 2 apply to both)
    1. enter a start value for the first attached object and an end value
       for the last and the plug interpolates between them
    2. enter a start value and then an interval that the value increases 
       with for every object
    3. (aligning) align to a point that lies a specified length ahead on the
       spline or to the base of the next object
    3. (positioning) attaches each object to the position the object is "named"
       see "NAME POSITIONING" for more help
    4. (positioning) the new feature that creates real cool effects :-)
       see "SCALE-SPLINE POSITIONING" for more help

  Use scaling:
    0. Scaling is not enabled and the scaling dialog will not be showed
    1. Scaling is enabled and a scaling dialog will appear


* Second dialog, Position type: 1

  Enter the unit you want to use in the "From:"-field
    1. Percent of the length of the spline
    2. Length along spline in Meter
    3. Splinepoints (integers give exact match but one can use 
       decimal numbers to specify positions between points)

  Enter the values you want in the corresponding from and two fields. The 
  first object is placed at the from-value and the last at the to-value. 
  The others are placed in between.

  Negative wrap:
    If this is 1 the plug treates a negative value as to be counted from 
    the end of the spline. Otherwise negatives are rounded to zero (internally).

  Positive wrap:
    If this is 1 the plug treates values that exceeds the splines length as
    if they had looped, i.e. 120% means 20% because the length is 100%. This 
    also applies to negative numbers (-120% becomes -20%). Otherwise the 
    numbers are truncated to the length of the spline.

* Second dialog, Position type: 2

  Exactly similar to "Position type: 1" but here the objects are placed
  at a start position and then each object is placed a specified interval
  ahead of the former.

* Second dialog, Position type: 3

  see "NAME POSITIONING"

* Second dialog, Position type: 4

  see "SCALE-SPLINE POSITIONING"


* Third dialog, Align type: 1 and 2

  Method: (the method of aligning)
    1. Vector: This aligns the Z-axis along the spline and the Y-axis is
               trying to point at a user-specified world-vector. (standard
               is straight up)
    2. World:  This rotates the objects by normal HPB values as they would
               be oriented if they were outside all hierarchy with the same
               values. (i.e. enter 0,0,0 and the axises will always point 
               along their world equivalents
    3. Object: Rotates the object by HPB but adjusts the objects as if they 
               were inside the spline-object. (i.e. enter 0,0,0 and the
               axises will always be along the splines axises)
    4. Spline: Enter the name of an align spline. The Z-axis will be aligned 
               along with the tangent and the Y-axis will try to point at the
               current position along the align spline. (this can provide exact
               aligning when other generalized methods run into troubles)

  Align (on/off):
    Tells the plug which rotations to adjust on the objects. If only heading is 
    1 then the objects wont pitch or bank. Keep in mind that this doesn't mean 
    pitch and bank is set to 0, they keep their previous values.

* Fourth dialog: Align type: 1 Align method: 1

  Enter a vector (the coordinates for a point to which one can imagine that a
  line from origo points to) in the appropriate fields. In you want to use the
  "To:" fields you need to put a 1 in the "To:" field. You can also specify a
  banking value.

* Fourth dialog: Align type: 2 Align method: 1
  
  Similar to the above except that this one uses a start-value and an interval
  instead (similar to the two position variants).

* Fourth dialog: Align type: 1 and 2 Align method: 2 and 3

  Enter HPB-values to use for the aligning described in the align method text.
  Align type one and two is differentiated in the same way as before.

* Fourth dialog: Align type: 1 and 2 Align method: 4

  This aligns by an align spline. The HPB-values are for manual correction (they
  are added to the rotation) and are used as in method 2 and 3.


* Third dialog: Align type: 3

  This align type utilizes method 1 and 4 above (here called 1 and 2) in a similar
  way except that it aligns the Z-axis, not along the tangent, but instead to a 
  point further along the spline.

  Distance type:
    This is the distance to the point the Z-axis is pointing at. Similar to the 
    position units (percent, meter and point) except that this also accepts 0.
    0 means that the Z-axis is pointed to the position of the next object
    (the last object is oriented along the tangent).

  Distance:
    Enter the distance to the align point. Big values gives more lookahead. Not
    used with distance type 0.


* Fifth dialog: Scaling: 1
   
  With scaling enabled you don't just have control over the posisition and rotation
  of your objects, but you also can adjust their scale. The easiest use is to just
  change the base scale over time, but you can also use several scaling splines and
  even morph them.

  Base-scale: 
    All scales are multiplied with this value, i.e. set it to two and all objects 
    will be twice the size. Can be animated over time.

  X-Y-Z-spline:
    The name of the scaling spline you wish to use for the scaling axis. If use X
    for all is enabled the X-spline is used for all the axises.

  Use X for all:
    see above

  Base: 
    This is the distance to the scale-spline that should generate a scale of 1. If
    the scale-spline-point is further away the scale is >1 and the other way around.
    If this is -1 the corresponding spline won't be used and the scale on that axis
    will be 1 (still multiplied with base scale though). If you want "WYSIWYG" you 
    should set the base value to your objects "radius" along that axis.

  About the scale splines: This is how the plug uses the scaling splines
    First it finds a point along the scaling spline at the same position as along the
    placing spline. Then it zeros the X-value of the point, i.e. places it on the ZY-
    plane. There it measures the distance from origo (0,0). That value is divided by 
    the corresponding base value to give the relative scale.

  How should they be placed:
    The scaling splines should be placed along the positive X-axis. I chose to make it 
    like this to enable easy animation of the position-spline (otherwise you would have
    to animate your scaling spline in a similar way by hand). See one of the example
    scenes if your still confused.

************************
*** NAME POSITIONING ***
************************

Two things was left out of the above description as they deserve an own section. One of 
the is name placing. This is a way to incorporate more advanced placing schemes than the
two basic method of start and end and start and interval can do. It's more like several
single placements, just that they are easily controlled. The key is that it uses the 
objects' names for placing. If an object is name "0.5" (and unit is %) then it's placed
at 50%. This dialog comes up if you enter "3" in position type:

Start:
  This is entered like in the other modes. The start value is added to the name value
  and can be useful if you want to move all objects together. 

Wrap:
  These two are also similar to the other modes.

Pos. scale:
  All positions are multiplied with this value (before being added to the start value). 
  Useful if you want to...well...make your objects come closer to each other.

Autoparsing:
  To make sure that the objects really are placed at their appropriate position, even
  when you change the name all the time, the plugs checks each objects name every time
  if this is 1. When you are satisfied you can set this option to 0 so no unnecessary
  processor power is spent. (though it doesn't bog it down that much) 
  Even though the plug checks the position every time it's called, due to the nature
  of C.O.F.F.E.E. it's only called when you move the time-line or redraw (ctrl-F). 
  There's nothing I can do about this.

Rename: (in the first dialog)
  But, isn't it very hard to name all the object? No, fortunately I have added an option
  to rename all the objects to their position using any of the other methods. Just attach
  your objects as normal, using type 1 or 2 for positioning, and enter 1 in "Rename:".
  All objects are now named accordingly. Go into the key again, put 0 into "Rename:" and
  3 into position type. Then make your changes by changing the name of the objects.


********************************
*** SCALE-SPLINE POSITIONING ***
********************************

This is the other section left out. It was a late addition to the plug and could be 
improved in many ways, but it does work and can create really cool results. This is
mostly thought of to be used with a lot of splines and a loft NURBS but I'm sure that
you can think of other uses as well. With the normal scaling you can just adjust the 
scale along the object. But what if wanted to create a shape that goes back again or 
make a hollow shape. Of course you could do this with name placing but it would be
a real PITA to do. With scale-spline positioning you can instead just draw the outline
of the object and the rest is magic.

When you enter 4 in the position type field you are faced with a dialog similar to name
placing. This is because it uses the same code to place the objects but it gets it's
values not from the names but from the discarded X-values of the X-scaling-spline.

It's recommended that you set units to meters and turn of wrap in the dialog.

See the example scene and examine the options to get a grip of how it works...

*********************************
*** MORHPING EXTERNAL SPLINES ***
*********************************

If you try to morph a scaling or align spline you will notice that it doesn't work.
This is because other objects' animations can't see the result. They still see the
base object. To fix this I made another plug (included) called globalize. It is placed 
on the morphing object and changes it's base object to reflect the morph. This has the
draw-back that the morph is irreversible, i.e. you can't just remove the morph-track, 
but that's a small prize for morphing scale splines :-)

You can also use globalize to globalize position, for example if you want to use
"Point at..." on a "Midpoint"-ed object you can with globalize. See the example
scenes if you're still confused...


Please mail me if you have any questions at cst@wineasy.se!
Mikael Sterner, XLent Plugs